Profile Integration Specification

The Profile Integration APIs provide synchronous and asynchronous options to upload and update subscriber records in Msgkart.

Run in Postman

---

Global API Configuration

Parameter	Required On Every Request	Value
Base URL	Yes	https://{{msgkart_host}}
Header	Yes	x-api-key: {{api_key}}
Header	Yes	Content-Type: application/json

---

Available Endpoints

1. Direct Profile Upload API (POST /api/v3/profile/upload)
   • Synchronous upload of up to 1,000 subscriber profiles directly in the request body.
2. Bulk Profile Upload API (POST /api/v3/profile/bulkupload)
   • Asynchronous import of large profile datasets via a presigned URL.

---

Standard Profile Body Schema

Top-level request body must contain a profile array. Field names are case-sensitive and must be exact lowercase — a misnamed field (e.g., naMe) is preserved in custom extras instead of mapping to the standard field.

Field	Type	Required	Description
phone	string	REQUIRED	Subscriber's mobile number (e.g. "917415908509"). Record is rejected if missing or invalid.
countrycode	string	Optional	ISO country code. Defaults to IN if omitted.
name	string	Optional	Full name of the subscriber.
age	integer	Optional	Age of the subscriber as an integer.
gender	string	Optional	Allowed values: male, female, or other.
dob	integer	Optional	Date of birth as Unix epoch seconds.
businesssubscriberid	string	Optional	Your system's unique user or customer ID (e.g. "CUST-98712").
* (custom fields)	any	Optional	Any other custom attribute (e.g., city, tier)

---

Ingestion Rules & Behaviors

• Idempotency: Ingestion is idempotent based on (businessId, phone) — an existing profile is updated in place.
• Partial Failure Handling: Batches with invalid phone numbers report status per-row while valid records in the same batch are successfully uploaded ("status": "success with errors").

---

Run in Postman